ElectroServer 3.7.2 Documentation

<root>

class ElectroServer

XMLSocket
  |
  +--ElectroServer


class ElectroServer
extends XMLSocket

This class is used to for communication between a Flash client and ElectroServer. For more information or help using ElectroServer, please visit http://www.electro-server.com


Author:
Jobe Makar, Electrotank, Inc

Version:
3.7.1


Event Summary

public
allZonesLoaded: Function
Event fired when a list of zones are loaded as a result of getAllZones

public
buddyLoggedIn: Function
Event fired when a buddy in your buddy list logs in

public
buddyLoggedOut: Function
Event fired when a buddy in your buddy list logs out

public
configurationLoaded: Function
Event fired when the configuration file has been loaded as a result of loadConfiguration.

public
connectionClosed: Function
Event fired when the connection to ElectroServer closes.

public
loggedIn: Function
Event fired as a result of the login method

public
loggedInUserCountUpdated: Function
Event fired when the number of logged in users is received as a result of getLoggedInUserCount.

public
messageReceived: Function
Event fired when you receive a public or private message

public
moveReceived: Function
Event fired when you receive a public or private move from another player

public
onConnection: Function
Event fired as a result of the connect method

public
onGetServerTime: Function
Event fired when the server time is loaded as a result of getServerTime.

public
onRoomsInZoneLoaded: Function
Event fired when the rooms in your zone are loaded as a result of the getRoomsInZone method.

public
pluginMessageReceived: Function
Event fired when the client receives a message sent from a plugin

public
rawMessageReceived: Function
Event fired when a raw message is received from a plugin

public
roomJoined: Function
Event fired as a result of the createRoom or joinRoom methods

public
roomListUpdated: Function
Event fired when the room list changes

public
roomVariablesUpdated: Function
Event fired when the room variables in your room change

public
userListUpdated: Function
Event fired when the list of users in your room updates

public
userLocationLoaded: Function
Event fired when the location of a user has been loaded as a result of getUserLocation

public
usersInRoomLoaded: Function
Event fired when the usrs in a specific room have been loaded as a result of getUsersInRoom

public
usersRenumbered: Function
Event fired when the AssignedNumber.value property on the users in your room changes

public
userVariableUpdated: Function
Event fired when the user variables on a user in your room have changed.

public
zoneChanged: Function
Event fired when you change zones

public
zoneUpdated: Function
Event fired when the number of users in the zone changes

Field Summary

public
inGame: Boolean
'true' if you are in a game room

public
isGameMaster: Boolean
'true' if you are the first on in a game room. (Not used much anymore)

public
myUser: Object
A pointer to the objec that represents you

public
password: String
Your password

public
username: String
Your username. Can alos be referenced like this: es.getUser().Name.value

Method Summary

public
addBuddy ( name: String )
Adds a buddy to your list

public
adminLogin ( tempUsername: String, tempPassword: String )
Special login for admin users

public
ban ( name: String, reason: String, expires )
Kicks and bans a user from the server

public
changeRoomDetail ( detail: String, value )
Changes one of many properties in a room

public
close ( )
Closes the connection with ElectroServer

public
connect ( tmp_ip: String, tmp_port: Number )
Connects you to the server

public
createGameRoom ( roomOb: Object )
Creates a room with specific flags

public
createRoom ( roomOb: Object, auto: Boolean )
Creates a room

public
createRoomVariable ( ob: Object )
Creates a room variable

public
createUserVariable ( name: String, value: String )
Creates a user variable

public
deleteRoomVariable ( name: String )
Deletes a room variable

public
deleteUserVariable ( name: String )
Deletes a user variable

public
getAllZones ( )
Loads a list of all the zones currently established

public
getBuddyList ( ): Array
Returns an array of your buddies

public
getDebug ( ): Boolean
Returns the debug state, true or false

public static
getInstance ( ): ElectroServer
Returns an instance of the ElectroServer class

public
getIP ( ): String
Returns the IP address that ElectroServer is using

public
getLoggedInUserCount ( )
Loads the number of connect users from the server

public
getPort ( ): Number
Returns the port that ElectroServer is using

public
getRoom ( )
Returns a reference to the room you're in

public
getRoomList ( )
Returns an array of rooms

public
getRoomsInZone ( tmp_zone: String )
Loads the list of rooms in a specific zone

public
getRoomVariables ( )
Returns an object full of variables

public
getServerTime ( )
Loads the time from the server

public
getUser ( )
Returns a reference to the object that represents you

public
getUserList ( )
Returns an array of users

public
getUserLocation ( name: String )
Loads the location of any user on the server

public
getUsersInRoom ( zone: String, room: String )
Loads a list of users for a specific room in a specific zone

public
getZone ( )
Returns a reference to the zone that you're in

public
joinGame ( room: String, password: String, type: String, zone: String )
Joins you to a game room

public
joinRoom ( room: String, password: String, zoneName: String, numbered: Boolean )
Joins you to a room

public
kick ( name: String, reason: String )
Kicks a user from the server

public
loadConfiguration ( )
Loads configuration file if logged in as an admin

public
login ( tempUsername: String, tempPassword: String, variables: Object )
Logs you into the server

public
logout ( disconnect: Boolean )
Logs you out of the server

public
pluginRequest ( plugin: String, method: String, parameters: Object )
Sends a message to a plugin

public
registerRawHandler ( name: String )
Tells ElectroServer which plugin to route raw messages to

public
removeBuddy ( name: String )
Removes a buddy from your list

public
sendMessage ( type: String, message: String, users: Array, variables: Object )
Sends a public or private message to the room or to an array of specific users

public
sendMove ( who, ob: Object )
Sends an object to the room or to an array of specific users

public
sendRaw ( str: String )
Sends a raw unchanged string to a plugin

public
setDebug ( val: Boolean )
Sets the debug property to true or false. If true it traces all inbound/outbound messages

public
setIP ( tempIP: String )
Sets the IP address to use when connecting to ElectroServer

public
setModeratorLabel ( val: Boolean, str: String )
Sets the moderator label to be appended to the front of a the name of all moderators

public
setPort ( tempPort: Number )
Sets the port to use when connecting to ElectroServer

public
updateUserVariable ( name: String, value: String )
Updates a user variable



Field Documentation

allZonesLoaded

public var allZonesLoaded: Function
Event fired when a list of zones are loaded as a result of getAllZones

This event is fired when the list of all zones on the server is loaded. An array of zone names is passed in. See also getAllZones.

Event parameters
zones List of zone names (Array)

buddyLoggedIn

public var buddyLoggedIn: Function
Event fired when a buddy in your buddy list logs in

This is fired as a result of one of two events:
1) That buddy just logged into the server
2) That buddy was already logged into the server but you just added him to your buddy list. The server fires this event so that you are updated to know that the buddy you just added is logged in.

See also addBuddy and removeBuddy.

Event parameters
username Name of buddy who just logged in (String)

buddyLoggedOut

public var buddyLoggedOut: Function
Event fired when a buddy in your buddy list logs out

This is fired as a result of one of two events:
1) That buddy just logged out of the server
2) That buddy was already logged out of the server but you just added him to your buddy list. The server fires this event so that you are updated to know that the buddy you just added is not online.

Event parameters
username Name of buddy that just logged out (String)

configurationLoaded

public var configurationLoaded: Function
Event fired when the configuration file has been loaded as a result of loadConfiguration.

Event fired when the configuration file has finished loading. The configuration XML file is passed into the callback function. See the provided admin client for example usage.

Event parameters
ob Object containing the parse configuration file.

connectionClosed

public var connectionClosed: Function
Event fired when the connection to ElectroServer closes.

Event fired when connection to the server is lost. If 'true' then the connection was closed due to forces out side of the Flash client (like ElectroServer closing it or a broken Internet connection). If 'false' then the connection closed because the close method was invoked. (Boolean)
See also connect and close.

Event parameters
ServerInitiated Boolean value.

inGame

public var inGame: Boolean
'true' if you are in a game room

isGameMaster

public var isGameMaster: Boolean
'true' if you are the first on in a game room. (Not used much anymore)

loggedIn

public var loggedIn: Function
Event fired as a result of the login method

When use use the login method to attempt a login, this event is eventually fired.

Event parameters
success (Boolean) Value is true if the login is a success.
error (String) Value exists if success = false.

loggedInUserCountUpdated

public var loggedInUserCountUpdated: Function
Event fired when the number of logged in users is received as a result of getLoggedInUserCount.

Event parameters
count The number of users logged into ElectroServer

messageReceived

public var messageReceived: Function
Event fired when you receive a public or private message

This is the most common way to receive chat messages.
Event parameters
type Either "public" or "private" (String)
message The message received (String)
from The name of the user that sent the message (String)
variables An object containing the message variables sent, if any (Object)

moveReceived

public var moveReceived: Function
Event fired when you receive a public or private move from another player

Users can send each other objects to make game creation much easier. See sendMove.

Event parameters
type Either "public" or "private" (Object)
object An object sent to you (Object)
from The name of the user that sent the move (Object)

myUser

public var myUser: Object
A pointer to the objec that represents you

password

public var password: String
Your password

pluginMessageReceived

public var pluginMessageReceived: Function
Event fired when the client receives a message sent from a plugin

Event fired when Flash receives a message from a plugin.

ElectroServer 3 has the ability to run custom-written plugins created using either Java or ActionScript. These plugins can send messages to individual users or to a room. When a message is received by a Flash client from a plugin, the name of the plugin is passed in. Also, an action name is passed in. This can be something like "CreateMonster". The plugin can also send an unlimited number of variables, which are found in the variables parameter.

Note: Please read ElectroServer 3 documentation on writing server plugins.

Event parameters
plugin The name of the plugin that sent the message (String)
action Action that the plugin wants you to take (String)
variables Object holding variables sent by the plugin (Object)

rawMessageReceived

public var rawMessageReceived: Function
Event fired when a raw message is received from a plugin

This is used by advanced users. Server-side plug-ins can be used to send messages of any format to a user. If the message is not of the typical ElectroServer XML protocol then this event is fired and the raw message is passed through.

This is mainly used for sending extremely condensed messages for real-time games.
See also registerRawHandler.

Event parameters
message Raw message as a string (String)

roomJoined

public var roomJoined: Function
Event fired as a result of the createRoom or joinRoom methods

Event fired when a you have been accepted or denied access to a room. When you invoke the createRoom method or the joinRoom method you will receive a roomJoined event as a response after the server processes your request. This event passes in an object with a success = true or false property. If success = false then this object also contains an error message.

Typical errors are due to invalid room passwords (when trying to join a password protected room), invalid room name, or room full.

Note: the reference to the room that you are in can also be retrieved by using the getRoom method.

Event parameters
results An ojbect containing 'success' boolean of true or false, and an 'error' property if needed (Object)
myRoom A reference to the object describing your room (Object)

roomListUpdated

public var roomListUpdated: Function
Event fired when the room list changes

Event fired when an update to the zone roomlist is received.
If updateType is "all": This is the initial roomlist received when joining a new zone (or logging in for the first time).
If updateType is "roomupdated": This is just a change in details for one room, such as its description, the number of users in that room, etc.
If updateType is "roomcreated": The room was just created.
If updateType is "roomdeleted": A room was jut removed. The 'roomReference' parameter is a string representing the name of the room just deleted. It is not a reference to the room object since it has been deleted.
Note: The reference to the room list can also be retrieved by using the getRoomList() method.

Event parameters
roomList An array of objects describing the list of rooms. (Array)
updateType "all", "roomupdated", "roomcreated", "roomdeleted" (String)
roomReference Reference to the room objec that was updated. (Object)

roomVariablesUpdated

public var roomVariablesUpdated: Function
Event fired when the room variables in your room change

Event fired when a room variable is created, modified, or removed. See createRoomVariable, deleteRoomVariable

Room variables are variables actually stored on the server in your room. They can be created, modified, or removed. By default, a room variable can be modified and will automatically be removed when the user that created it leaves the room. However, a room variable can be flagged to be persistent which means that it will nto delete when the user that creates it leaves the room. Also, a room variable can be flagged as locked, which means that once locked it can no longer be modified (but can still be deleted).

Event parameters
type "all", "updated", "created", "deleted" (Object)
roomVariables An object containing all of the room variables. (Object)
name String name of the variable updated. (blank if type=="all") (Object)

userListUpdated

public var userListUpdated: Function
Event fired when the list of users in your room updates

Event fired when the users in your room changes. When you first join a room you get the full user list and type is "all". After that you only receive "userjoined" and "userleft" updates.

If type is "all" then the userRefrence parameter is blank. If type is "userjoined" then the userReference parameter contains a reference to the user object. If type is "userleft" then the userReference parameter is a string name of the user that left (not a reference to the object as the object has been removed).
See also getUserList

Event parameters
userList Array of user objects (Array)
type "all", "userjoined", "userleft" (String)
userReference Name of the user that joined or left (String)

userLocationLoaded

public var userLocationLoaded: Function
Event fired when the location of a user has been loaded as a result of getUserLocation

This event is fired as a result of getUserLocation. It tells you the zone and room that a specific user is in. See getUserLocation for more information.

Event parameters
username Username (String)
zone Zone that the user is in (String)
room Room that the user is in (String)

username

public var username: String
Your username. Can alos be referenced like this: es.getUser().Name.value

usersInRoomLoaded

public var usersInRoomLoaded: Function
Event fired when the usrs in a specific room have been loaded as a result of getUsersInRoom

As a result of getUsersInRoom this event is fired. An array of user objects with a 'name' property is passed in. Also, the zone name and room name of the users are passed in.

Note: we are using objects with a 'name' property to leave open the chance to add more useful properties to this in the future, like userVariables. Currently you cann't load userVariables of a user who is in another room.

Event parameters
users Array of objects (Array)
zone Name of zone that room is in (String)
room Name of room that users are in (String)

usersRenumbered

public var usersRenumbered: Function
Event fired when the AssignedNumber.value property on the users in your room changes

Event fired when the users in your room have been renumbered. By default, when creating a room the Numbered attribute is 'false', meaning the users in that room are not numbered. However, when Numbered is 'true', the users in the room are numbered.

Why numbered users can be usefull
When creating multiplayer games that use more than two players it is quite a task to keep track of the order of users in the game. What happens if someone leaves the game in the middle and it is their turn to move? Due to Internet latency and the various scenarios by which a person can leave a game it is difficult to guarantee no problems.

With numbered users you always know the order of the users. If it is number 3's turn to move and then number 3 leaves the room, well then it is still number 3's turn because number 4 just shifted down a position. Since this is kept on the server there is no chance of synchronization problems.

This concept is not the easiest to understand initially, it may help to view sample FLA files.

Note: the userList is passed in to the event handler. The userList can also be retrieved using the getUserList method.

Note: if you use server-side plugins then you can achieve the same benefits much more easily. The benefits being a centralized location that knows whose turn it is.

Event parameters
userList Array of user objects. (Array)

userVariableUpdated

public var userVariableUpdated: Function
Event fired when the user variables on a user in your room have changed.

This event is fired when a uservariable is created or updated that is associated with a user in your room.
See also createUserVariable and deleteUserVariable.

Event parameters
user object referencing the user who owns the variable (Object)
type Either "created" or "updated" (String)
name Name of the variable created or updated (String)

zoneChanged

public var zoneChanged: Function
Event fired when you change zones

Event fired when you enter a new zone. Simply gives you the name of the zone that you have just entered.

A zone is a collection of rooms much like a room is a collection of users. When in a zone you get information on the other rooms in your zone. You have no knowledge of any of the other zones.

Event parameters
name The name of the newly joined zone.

zoneUpdated

public var zoneUpdated: Function
Event fired when the number of users in the zone changes

Event fired when the number of users in the zone changes. Simply gives you the number of users in your zone when ever that number is changed.

Event parameters
numUsers Number of users in the zone


Method Documentation

addBuddy

public function addBuddy(name: String)
Adds a buddy to your list

ElectroServer supports the idea of "buddies". You can add a buddy to your buddy list. You are told when ever a buddy logs into the server or logs out of the server with the buddyLoggedIn and buddyLoggedOut events. The moment you add a buddy to your list you are informed if that buddy is logged in or not. See also removeBuddy, buddyLoggedIn, buddyLoggedOut, getBuddyList

Parameters:
name
Name of user to add
Example:
es.addBuddy("jobem");

adminLogin

public function adminLogin(tempUsername: String,
 tempPassword: String)
Special login for admin users

This method is exactly the same as the login method except that it informs the server that this user is trying to login as an administrator. There is only 1 administrator per instance of ElectroServer. The administrator's username and password are set in the configuration.xml file.
Administrators, once logged in, have a greater level of access than do users or moderators.

Parameters:
tempUsername
Username of admin
tempPassword
Password of admin
Example:
es.adminLogin("system", "electroserver");

ban

public function ban(name: String,
 reason: String,
 expires)
Kicks and bans a user from the server

Kicks a user from the server and bans them from logging in again. The 'time' parameter is the length of time in minutes that a user should be banned from the server. If "-1" then the user is banned until the the server is restarted.

Parameters:
name
Name of user to be banned
reason
Reason for banning
expires
The amount of time that the user should be banned in minutes
Example:
The following bans someone for 20 minutes. es.ban("jobem", "You have repeatedly been mean.", 20);

changeRoomDetail

public function changeRoomDetail(detail: String,
 value)
Changes one of many properties in a room

Change attributes of the room that you are currently in. Acceptable 'details' are:
description The value is an object (just like in createRoom and createGame). The properties of the object are description and attributes. Attributes is another object that can hold any number of custom variables.
updatable The value is true or false. If true, then the room will receive updates about the zone. If false then it will receive no updates accept regarding itself.
hidden The value is true or false. If true then the room is not seen by any other room. If false then the room is seen by other rooms within the zone.
capacity The value is a number. This changes the max capacity fo the room. If the value is -1 then there is no limit.
password The value is a string or blank. If blank then the room is switched to having no password. If not blank then the password of the room is changed to the new value.

Parameters:
detail
The name of the attribute to change
value
The new value for the attribute that is changing
Example:
Makes a room hidden:
es.changeRoomDetail("hidden", true);
Changes the password of your room:
es.changeRoomDetail("password", "myNewPass");
Changes the description object:
var ob:Object = new Object();
ob.attributes = new Object();
ob.description = "A cool room";
ob.attributes.some_useful_variable = "asdf";
es.changeRoomDetails("description", ob);

close

public function close()
Closes the connection with ElectroServer

Closes the connection to ElectroServer. As a result the connectionClosed event is fired. See also connectionClosed.

Example:
es.close();

connect

public function connect(tmp_ip: String,
 tmp_port: Number)
Connects you to the server

Creates a socket connection with ElectroServer using an IP and Port specified. Alternatively, the ip and port can be set using the setIP and setPort methods and left blank in this method. See also onConnection.

Explanation for beginners
ElectroServer is a socket-server, a piece of software written in Java that resides on a remote server somewhere (or your own personal computer for testing). When the ElectroServer software is started it "binds" itself to a specific IP address and "listens" for communication requests over a specific port. The connect() method is used to establish a connection with ElectroServer. By specifying the IP address and port that ElectroServer uses you can connect to it. This connection is called a persistent connection. It is persistent because the connection exists until it is closed by the Flash client, the server, or by killing the Flash client (leaving the web page).
While this connection exists data can be passed from the Flash client to the server or from the server to the Flash client without either side requesting the data. This data is intercepted and used by making use of many of the various methods and events of the ElectroServer object.
If you are truly a beginner and are having trouble understanding all of this, then please take a look at some open-source FLA examples that use the ElectroServer class.

Parameters:
tmp_ip
The ip address of ElectroServer
tmp_port
The port over which ElectroServer is listening
Example:
Usage 1:
es.setIP("127.0.0.1");
es.setPort(9875);
es.connect();
Usage 2:
es.connect("127.0.0.1", 9875);

createGameRoom

public function createGameRoom(roomOb: Object)
Creates a room with specific flags

Creates a room for a game. This method accepts an object with exactly the same properties as the createRoom method does. Please see that method for full details.
The flag that shows that this room is a game room is found in the room object as: roomOb.description.attributes.isGameRoom, and has a value of 'true'.

Note: The createGameRoom method differs from the creatRoom method only because it flags the room as being a game room. When the room is created, modified, or removed, the same events are fired as with a regular room. By flagging a room as a game room it is easier to show a difference in the room list.

Note: This method is not used very frequently. Developers, in general, prefer to just use createRoom.

Parameters:
roomOb
Object describing room to be created
Example:
var roomOb:Object = new Object();
roomOb.zone = "Game Zone";
roomOb.roomName = "DiePleez";
es.createGameRoom(roomOb);

createRoom

public function createRoom(roomOb: Object,
 auto: Boolean)
Creates a room

Creates a room in a specific zone and then joins you to that room. See below for description of each of the configurable properties of a room.

Note: If you attempt to create a room that already exists then internally the ElectroServer class will receive an error and you will automatically be joined to that room (since it exists). If that is not behavior that you want in your application, then set the 2nd parameter in createRoom to false.

Properties of the room object

The roomOb object can contain many properties to customize the room. Some of them are required while others are not.

password If blank the room is not password protected. If it contains anything then the room is password protected.

userVariablesEnabled If blank or 'false' then user variables are not enabled for this room (increases performance). If 'true', then user variables are enabled for the room. See createUserVariable, login, or userVariableUpdated for more information.

hidden If blank or 'false' then the room is not hidden. If 'true', then the room is hidden and cannot be seen by the other rooms in your zone. This is often used for game rooms.

zone This is the zone in which you want to create a room. If the zone does not yet exist then it will be created. Required.

roomName The name of the room to be created. Required.

numbered If blank or 'false' the room does not number its users. If 'true' then it does. See the usersRenumbered event.

capacity If blank or -1 then the room has no maximum size. If the number is greater than 0 then the room created can only grow to a certain user size.

description Can be left blank or be a string describing the room.

updatable If blank or 'true' then the room is updatable. If 'false' then it is not. A room that is updatable receives zone updates and roomList updates. If it is not updatable then it only receives updates regarding itself (userListUpdates, etc). This increases performance for that room, recommended for games.

FloodingFilterEnabled If blank it is set to false, which means it's not enabled. When enabled the room checks to see if users send messages too quickly to the server. This is called flooding. If flooding is detected then the user is kicked. Flooding properties can be configured in the configuration.xml file.

userListEnabled The default is true. When enabled, the users in a room are informed of the list of users in that the room. Also the room receives userListUpdated events when users join or leave. If set to false, then ElectroServer sends no information or updates about the users in a room. This can be useful to set to false in rooms that have many users to cut down on message traffic.

roomVariables Can be left blank if you don't want to create a room with room variables. This is an array of objects, each of which describes a room variable. The properties of a room variable are 'name' (name of variable), 'data' (value of variable), 'persistent' (optional Boolean), 'locked' (optional Boolean). Room variables can be created using the createRoomVariable method. See that method for more details.

attributes Optional property. This is an object that can contain variables or arrays. It is attached to the room much like the room description is. This means that it is accessible by people in other rooms.

plugins Optional property. ElectroServer 3 supports the ability to use server-side plugins. You can access custom-written ActionScript or Java plugins from Flash on the server. But in order to access them they must be instantiated when creating a room. This property is an array of objects. Each object represents a plugin that you want to instantiate for the room. The 'name' variable on that object is the name of the plugin. The object can contain another object called 'variables' if you want to pass variables into the plugin. Using plugins is an advanced feature that requires a moderate level of understanding of ElectroServer and the ElectroServer object.

Parameters:
roomOb
An object representing the room to be created
auto
Boolean value, default is true. If true and the room that you are creating already exists, then you'll be joined to that room.
Example:
Here is the most basic way to create a room:
var roomOb:Object = new Object();
roomOb.zone = "Chat Area";
roomOb.roomName = "Lobby";
es.createRoom(roomOb);
Here is a long-winded example of creating a room with all properties used except plug-ins:
var roomOb:Object = new Object();
roomOb.zone = "Chat Area";
roomOb.roomName = "Lobby";
roomOb.hidden = false;
roomOb.numbered = false;
roomOb.userVariablesEnabled = false;
roomOb.description = "You can chat all day long in this room!";
roomOb.password = "";
roomOb.capacity = -1;
roomOb.updatable = true;
//room vars
roomOb.roomVariables = new Array();
var ob:Object = new Object();
ob.name = "BackgroundMusic";
ob.data = "AmbientSounds";
roomOb.roomVariables.push(ob);
//end room vars
es.createRoom(roomOb);
Here is an example creating a room with two plugins:
var roomOb:Object = new Object();
roomOb.zone = "Chat Area";
roomOb.roomName = "Lobby";
roomOb.plugins = new Array();
roomOb.plugins.push({name:"ShootEmUpPlugin"});
roomOb.plugins.push({name:"ScoreSaverPlugin"});
es.createRoom(roomOb);

createRoomVariable

public function createRoomVariable(ob: Object)
Creates a room variable

Creates or updates a variable in the room on the chat server. The variable can be flagged as locked and/or persistent.
Deeper explanation
ElectroServer supports room variables. This means that a Flash client can create a variable at the room level that is actually stored in ElectroServer. While ElectroServer is the 'master' of all of these room variables, each Flash client knows about all of the room variables as well. When ever a room variable is created, modified, or deleted, every user in that room is notified and the ElectroServer object updates this information internally.
When room variables are created, modified, or deleted an event in the ElectroServer object called roomVariablesUpdated is fired. See that event for more information. The room variables can be accessed at any time by using the getRoomVariables method.
Room variables can be created and then modified. A room variable can be created and locked so that it cannot be modified any more (but can still be deleted). And a room variable can be flagged as persistent, which means that it is not automatically deleted when the user that created it leaves the room.
Why room variables are useful
With room variables you have a centralized location to store data. If, for instance, you wanted to create an avatar chat where chracters could walk around and chat, then room variables can help in the following way:
For each user in the room you can create a room variable that stores his position and the type of character that he is using. Then when someone new joins the room their Flash client just uses the room variables to determine where to place the avatar characters. Everytime someone moves their avatar character then they send a room variable update to update its postion on the server.
Without room variables the way that the above would be accomplished would be by sending information separately to everyone in the room round-robin style. This is not good practice, causes synchronization issues, and uses more bandwidth.
Here are two good examples of persistent room variables (meaning that they do not delete when the user that created them leaves the room):
1.) A Flash white board. You can use persistent room variables to store the drawings. Then as people leave and new people come into the white board they can see everything.
2.) For a multiplayer game you can build something in the world or leave something behind (like scorch marks form an explosion). When you leave the variable remains and so everyone can see your contribution.
Here is a good example of a locked room variable:
Let's say you wanted to create a scavenger hunt game. This game has several people in it and there are say, 10 objects to collect. You can collect one by moving your character to the object and pushing a special key. Well, what if two people reach the same object at the same time? How do you know who actually collected it? There is no way to do this without server-side help, like locked room variables.
If your username is "jobem" and you collect a "gold cup" then you can set a locked user variable into the room called:
goldCup = "jobem"
When everyone receives this room variable update they can flag that object as collected. If someone tries to collect the object in that 100 or so miliseconds of Internet latency then they will still fail because they will not be able to create the room variable as it is already locked!
To 'clean up' the game to start over you would then have to delete each of those room variables.

Parameters:
ob
An object containing many optional properties. Here are those properties:
name The name of the room variable to be created or updated. (String)
data The value of the room variable to be created or updated. (String)
locked Optional property. If true then the variable can not be modified once created in the room, however it can still be deleted. The default value is false. (Boolean)
persistent Optional property. If true then the variable remains in the room after the user that created it leaves the room. If false then the variable is deleted when the user who created it leaves the room. The default value is false.
Example:
The following code creates a room variable on the server in your current room. The variable is not locked and will be removed when you leave the room:
var ob = new Object();
ob.name = "NumberOfBadGuys";
ob.data = "30";
es.createRoomVariable(ob);
The following code creates a room variable on the server in your current room. This variable is locked, meaning that it cannot be modifed (only deleted). It is also persistent, which means it will not die if you leave the room:
var ob:Object = new Object();
ob.name = "secretDoorUnlocked";
ob.data = "true";//this is a string because all room variables are strings
ob.locked = true;
ob.persistent = true;
es.createRoomVariable(ob);

createUserVariable

public function createUserVariable(name: String,
 value: String)
Creates a user variable

Creates a variable stored on the server associated with the user that created it. As the user moves from room to room the variable comes with him. When the user enters a room or when any uservariable is created, removed, or modified, all users in that room are notified of the change. See also deleteUserVariable, userVariableUpdated. Note: There is an example file installed with ElectroServer called UserVariablesTest.fla that is very helpful.

Parameters:
name
Name of the user variable
value
Value of the variable
Example:
To create a user variable on yourself: es.createUserVariable("myIcon", "happy face"); To trace everyone's user variables:
var userlist:Array = es.getUserList();
for (var i=0;i<userlist.length;++i) {
	var user:Object = userlist[i];
	var userVariables:Object = user.userVariables;
	trace("User variables for "+user.Name.value);
	for (var name in userVariables) {
		trace(" variable name: "+name);
		trace(" variable value: "+userVariables[name]);
	}
}

deleteRoomVariable

public function deleteRoomVariable(name: String)
Deletes a room variable

Deletes the room variable with the name passed in, even if it is a locked room variable. For more information on room variables, see createRoomVariable and getRoomVariables.

Parameters:
name
The name of the room variable to delete
Example:
es.deleteRoomVariable("welcomeMessage");

deleteUserVariable

public function deleteUserVariable(name: String)
Deletes a user variable

Deletes an existing user variable. See also createUserVariable, updateUserVariable.

Parameters:
name
Name of variable to be deleted
Example:
es.deleteUserVariable("myIcon");

getAllZones

public function getAllZones()
Loads a list of all the zones currently established

Loads the list of zones on the server. When loaded 'allZonesLoaded' event is fired. See also allZonesLoaded.

Example:
es.allZonesLoaded = function(zones:Array) {
	trace("--All Zones--");
	for (var i=0;i<zones.length;++i) {
		trace(zones[i]);
	}
}
es.getAllZones();

getBuddyList

public function getBuddyList(): Array
Returns an array of your buddies

This method returns the list of your buddies as an array. Each element in the array is an object that has the following properties: username - name of the buddy isOnline - Boolean (true for online) ob.status - String (offline or online) ob.label - Matches the username. For use with list box component See also addBuddy, removeBuddy, buddyLoggedIn, buddyLoggedOut

Example:
var myBuddies:Array = es.getBuddyList();
for (var i=0;i<myBuddies.length;++i) {
	var buddy:Object = myBuddies[i];
	trace(buddy.username);
}
Alternative usage: Also works with a list box component
myList_lb.dataProvider = es.getBuddyList();

getDebug

public function getDebug(): Boolean
Returns the debug state, true or false

Returns either true or false. You can change the debug state using setDebug(true/false);. See also setDebug.

Example:
var debugVal:Boolean = es.getDebug();

getInstance

public static function getInstance(): ElectroServer
Returns an instance of the ElectroServer class

The ElectroServer class is a singleton. You don't use it like this: var es = new ElectroServer(). You get the instance of ElectroServer like this: var es = ElectroServer.getInstance();

Example:
var es:ElectroServer = ElectroServer.getInstance();

getIP

public function getIP(): String
Returns the IP address that ElectroServer is using

Returns the IP address of ElectroServer

Example:
var ip:String = es.getIP();

getLoggedInUserCount

public function getLoggedInUserCount()
Loads the number of connect users from the server

Loads the total number of users connected to ElectroServer. When load is complete loggedInUserCountUpdated is fired. See also loggedInUserCountUpdated.

Example:
es.loggedInUserCountUpdated = function(count:Number) {
	trace("users connected: "+count);
}
es.getLoggedInUserCount();

getPort

public function getPort(): Number
Returns the port that ElectroServer is using

Returns the port that ElectroServer is using

Example:
var port:Number = es.getPort();

getRoom

public function getRoom()
Returns a reference to the room you're in

Returns the room object that describes your room. This object contains information about your room such as it's name, number of users in it, if it is password protected, its maximum capacity, and all of the room variables. For more information about the properties on the room object see getRoomList.

Returns:
Object that describes the room that you are in.

Example:
var myRoomName:String = es.getRoom().Name.value

getRoomList

public function getRoomList()
Returns an array of rooms

Returns the list of rooms in your zone as an array. Each element in the array in an object describing a room. From each element you gain information about a room such as its name, description, number of users, maximum number of users allowed, and if the room is password protected.
Note: A zone is a collection of rooms much like a room is a collection of users.
Properties of each room object returned in the array
Each element in the room list array is an object describing a room. Here are the properties of a room object:
Name.value The name of the room
Description.value The room description if there is one.
attributes (an object containing the following room properties):
attributes.users The number of users in the room
attributes.MaxCapacity The maximum number of users allowed in this room. '-1' means there is no limit.
attributes.IsPasswordProtected A boolean value specifying if the room requires a password to enter.
attributes.Users The number of people in that room.
See also createRoomVariable, deleteRoomVariable.

Returns:
An array. Each element in the array is an object.

Example:
The code that follows is a simple way to just display the rooms in your current zone in an HTML enabled text filed. Note: this does not make use of the the other properties of the room objects.
function showRooms() {
	var roomListBoxStr:String = "";
	var roomlist:Array = es.getRoomList();
	for (var i = 0; i<roomlist.length; ++i) {
		var room:Object = roomlist[i];
		roomListBoxStr += room.name.value+"<br>";
	}
	roomListBox.htmlText = roomListBoxStr;
}

getRoomsInZone

public function getRoomsInZone(tmp_zone: String)
Loads the list of rooms in a specific zone

Loads a room list for a specific zone. When loaded 'onRoomsInZoneLoaded' is fired. See also onRoomsInZoneLoaded.

Parameters:
tmp_zone
The name of the zone
Example:
es.onRoomsInZoneLoaded = function(roomlist:Array, zoneName:String) {
	trace("Room list loaded for " +zoneName);
	for (var i=0;i<roomlist.length;++i) {
		var room:Object = roomlist[i];
		trace(room.Name.value);
	}
}
es.getRoomsInZone("Golf Zone");

getRoomVariables

public function getRoomVariables()
Returns an object full of variables

Returns an object whose properties are ElectroServer room variables. Each property of this object is a variable stored at the room level actually on the server. These properties can be accessed either directly (like object.myVariable) or by using a 'for...in' loop. See the example.
See also createRoomVariable, deleteRoomVariable

Returns:
An object. Each property in the object is a variable for that room.

Example:
To simply show all of the room variables for a room in the output window, use the following code:
function showRoomVariables() {
	var roomVariables:Object = es.getRoomVariables();
	for (var i in roomVariables) {
		trace(i+"="+roomVariables[i]);
	}
}
Or you can access a room variable directly like the following:
var musicLoop:String = es.getRoomVariables().musicLoop;

getServerTime

public function getServerTime()
Loads the time from the server

Loads the server time in miliseconds. This absolute number itself is rarely useful. This is usually useful when trying to syncrhonize the client with logic on the server. When the time is loaded the onGetServerTime event is fired. See also onGetServerTime.

Example:
es.onGetServerTime = function(time:Number) {
	trace("server time: "+time);
}
es.getServerTime();

getUser

public function getUser()
Returns a reference to the object that represents you

Every user in the userlist has an object that contains information about that user. This method returns the object that represents you.

Properties on user object
Name.value The username
userVariables Uservariables associated with you. See createUserVariable.
AssignedNumber.value If the room is numbering users, then this has your unique number in it.

Returns:
Returns an object representing you.

Example:
The following just traces your username:
trace(es.getUser().Name.value);
The following returns the number associated with you in a game.
var myNum:Number = es.getUser().AssignedNumber.value;

getUserList

public function getUserList()
Returns an array of users

Returns an array of objects each of which describes a user in your room. The properties of each object are 'Name.value' which is a string, and 'moderator' which is a boolean value. If 'moderator' is true then that user is a moderator. There is also a property called 'userVariables'.
User variables are variables saved on the server and associated with a specific user. This is useful for carrying information about a user around from room to room. See createUserVariable for more information on user variables.
See also getUser.

Returns:
An array of objects. Each object describes a user in your room.

Example:
This gets the user list, loops through it, and traces out the names of the users.
var list:Array = es.getUserList();
for (var i=0;i<list.length;++i) {
	var user:Object = list[i];
	trace(user.Name.value);
}

getUserLocation

public function getUserLocation(name: String)
Loads the location of any user on the server

Loads the location of a user from the server. When loaded the 'userLocationLoaded' event is fired.

Parameters:
name
The name of the user
Example:
es.getUserLocation("jobem");
//Capture the response
es.userLocationLoaded = function(username, zone, room) {
	trace(username+", "+zone+", "+room);
};

getUsersInRoom

public function getUsersInRoom(zone: String,
 room: String)
Loads a list of users for a specific room in a specific zone

Loads a list of users in a specific room and zone. When loading is comple, the 'usersInRoomLoaded' event is fired

Parameters:
zone
The zone that the room is in
room
The room you are interested in
Example:
es.usersInRoomLoaded = function(userlist:Array, roomName:String, zoneName:String) {
	trace("--user list loaded for zone: "+zoneName+", roomName");
	for (var i=0;i<userlist.length;++i) {
		var user:Object = userlist[i];
		trace(user.Name.value);
	}
}
es.getUsersInRoom("Chat Area", "Lobby");

getZone

public function getZone()
Returns a reference to the zone that you're in

Returns an object representing your current zone. This object has the following properties:
numUsers - This is number of people in your zone.
name - This is the name of the zone that you are in.

Returns:
An object representing the zone that you are in.

Example:
var myZone:Object = es.getZone();
trace(myZone.name);
trace(myZone.numUsers);

joinGame

public function joinGame(room: String,
 password: String,
 type: String,
 zone: String)
Joins you to a game room

A game exists in a room. To join that game you must join that room. This method handles that for you.
If you pass in a playerType of "player" then you are joining that game to become a player. If you pass in a playerType of "spectator" then you are just there to watch.

Parameters:
room
The name of the room
password
The password for the room, if any.
type
Either "player" or "spectator" depending on why you're joining the game.
zone
The name of the zone if it differs from the one you're currently in.
Example:
es.joinGame("Mini Golf 173", "", "player");

joinRoom

public function joinRoom(room: String,
 password: String,
 zoneName: String,
 numbered: Boolean)
Joins you to a room

Joins you to a room in a specified zone. You can only join a room that has already been created. If a room has not yet been created then you must first create it using the createRoom method, and then ElectroServer will automatically join you to that room. See also roomJoined.

The password parameter can be left blank or can be "" if no password is needed. The 'zone' parameter can be left blank if you are already in a zone and the room that you are joining is in the same zone. However, if you have just logged in to the server and have not yet joined a room, then the zone must be specified.

More detail for beginners A room is a collection of users. In a room you can see other users in your room. When in a room you cannot see users in any other rooms (you only know that they other rooms exist and you know how many people are in them). In a room you can send messages which are received by other people in that room.

Much like a room is a collection of users, a zone is a collection of rooms. In a zone you can see all of the rooms in that zone, but you have no information if any other zones exist or any information about other zones.

Parameters:
room
Name of the room to join
password
Password for the room, if any (optional)
zoneName
The name of the zone that the room is in. Only needed if it is in a different zone then you are currently in. (Optional)
numbered
Either 'true' or 'false'. If 'true', then you are given a number in the room. This can be useful in some games. (Optional)
Example:
es.joinRoom("Lobby", "", "Chat Area"); or,
es.joinRoom("SecretRoom", "secret_password", "Chat Area");
or if you are already in a zone and want to join another room in that zone with no password, then it can be condensed to this:
es.joinRoom("Game talk");

kick

public function kick(name: String,
 reason: String)
Kicks a user from the server

Kicks a user from the server. This is only available to moderator level users. A moderator is specified by a specific username/password combination found in the configuration.xml file.

Parameters:
name
Name of the user to be kicked
reason
Reason for kicking
Example:
es.kick("jobe", "for being too cool");

loadConfiguration

public function loadConfiguration()
Loads configuration file if logged in as an admin

Loads the configuration file for the server (only a logged-in admin can do this). Once the configuration file is loaded the configurationLoaded event is fired.
The configuration file contains all of the configurable information for ElectroServer 3. It is used by admins to configure the server. They can modify many things such as the language filter, plug-ins, and banned users.

Admin functionality is not fully documented as it is expected that you will use the provided admin client.

Example:
es.configurationLoaded = function(ob:Object) {
	//config loaded
}
es.loadConfiguration();

login

public function login(tempUsername: String,
 tempPassword: String,
 variables: Object)
Logs you into the server

Before you can use any of the server functionality you must login to the server. Using this method is how that is accomplished. If ElectroServer has not been configured to accept passwords, then the password field is not required.

The password field is used by the server in one of two ways:
1) To verify that you are a moderator for the server. A moderator has extended abilities such as kick and ban.
2) The password is passed through a custom-written login event handler for the server. This would be in place to verify login information against a database.

The login method returns nothing. However, once the server has either accepted or denied your login request the loggedIn event is fired.

Parameters:
tempUsername
The username to use
tempPassword
The password to use. (Optional)
variables
An object containing variables to be sent to ElectroServer. This is useful when using a custom server-side login event handler. (Optional)
Example:
function loginResponse(success:Boolean, error:String) {
	//This function is called when the server responds after a login request is sent
	if (success) {
		//properly logged in
		gotoAndStop("Chat")
	} else {
		//not properly logged in, there was an error
		msg.text = error;
		trace(error);
		gotoAndStop("Error")
	}
}
es.loggedIn = loginResponse;
es.login("jobem");

logout

public function logout(disconnect: Boolean)
Logs you out of the server

This method logs you out of ElectroServer. If the parameter is true then it also disconnects you from ElectroServer.

Parameters:
disconnect
Boolean value. If true then you are disconnected from ElectroServer too. If false, then your connection persists and you can re-login.
Example:
es.logout();

pluginRequest

public function pluginRequest(plugin: String,
 method: String,
 parameters: Object)
Sends a message to a plugin

Sends a request to a custom-written plugin in ElectroServer. You must specify the name of the plugin and the method to be executed. The plugin accepts this information and returns a result if necessary.
ElectroServer 3.0 has the ability to accept plugins. Plugins can be written in Java or ActionScript. With ElectroServer plugins you can easily extend the functionality of ElectroServer and create applications such as multiplayer real-time games! Plugins are super powerful and super cool. Check out http://www.electro-server.com for more information on them.

Parameters:
plugin
Name of the plugin that you are trying to communicate with. This is specified in the configuration.xml file.
method
This is a string that the plugin will use to determine what to do with your request.
parameters
This is an optional parameter, an object of name value pairs. All values should be strings.
Example:
The following could work with a plugin written to store white board data. The white board could then inform all new users to the room of the current state of the board. This code could tell the plugin to draw a line. It is then up to the plugin to send this information to the other people in the room.
var parameters:Object = new Object();
parameters.startx = 200;
parameters.endx = 300;
parameters.starty = 37;
parameters.endy = 110;
parameters.color = "blue";
es.pluginRequest("WhiteBoardScriptPlugin", "DrawLine", parameters);

registerRawHandler

public function registerRawHandler(name: String)
Tells ElectroServer which plugin to route raw messages to

This is an advanced feature. You call this method and pass in the name of an ElectroServer plugin. Then, if the client needs to send a custom formatted message to the server it can. All messages whose formats are not recognnized are forwarded on to the plug-in. Instead of a 500 byte XML message you could send a 20 byte custom string. This works well for high performance real-time games. See also sendRaw.

Parameters:
name
The name of the plugin
Example:
es.registerRawHandler("ShootemUpPlugin");

removeBuddy

public function removeBuddy(name: String)
Removes a buddy from your list

Removes a user from your buddy list

Parameters:
name
Username to remove
Example:
var user:String = "jobe";
es.removeBuddy(user);

sendMessage

public function sendMessage(type: String,
 message: String,
 users: Array,
 variables: Object)
Sends a public or private message to the room or to an array of specific users

Send a message to the room or an array of specific users. With this method a message can be sent to a room (public message) or to a list of users (private message). You can send an unlimited list of variables along with any message (see example).

When a message is sent it goes to ElectroServer where it is then broadcast to the appropriate people (the room or private users). When the message is received by these users the messageReceived event is fired. See the messageReceived event for more information.

Note: The variables parameter to this method is optional.
Note: Private messages can be sent to a user anywhere on the server. Each user has a unique username (you can't have two "john" users at the same time). So when you send a private message to "john" it will find him in any room in any zone.

Parameters:
type
To send to the room this should be "public" or "all". To send to an array of users it should be "private".
message
The string message to send.
users
The array of users to send to. Each element should be a username.
variables
An object of name value pairs. Each value should be a string.
Example:
Here is the most simple example of sending a message to a room:
var message:String = "Hello world!";
es.sendMessage("public", message);
Here is a simple of example of how to send a message to a room with variables:
var message:String = "Hello world!";
var variables:Object = new Object();
variables.textColor = "yellow";
variables.soundToPlay = "boink";
es.sendMessage("public", message, variables)
Here is a simple example of how to send a private message to three people with variables:
var message:String = "Hello world!";
var variables:Object = new Object();
variables.textColor = "yellow";
variables.soundToPlay = "boink";
var users:Array = new Array();
users.push("Kelly");
users.push("Robert");
users.push("Mike");
es.sendMessage("private", message, users, variables);

sendMove

public function sendMove(who,
 ob: Object)
Sends an object to the room or to an array of specific users

Sends an object to the room or to an array of specific users. Using the sendMove method you actually send an ActionScript object to the room or to specific users. The object is serialized using the WDDX protocol, sent to the user, deserialized, and used.
When the user receives the object the moveReceived event is fired.
Note: The WDDX serialization ActionScript classes are used courtesy of Branden Hall.

Parameters:
who
Should be the string "all" or an array of user names. (String or Array)
ob
An ActionScript object to send to the other users (Object)
Example:
Here is a simple example of how to send a chess move to another user.
var ob:Object = new Object();
ob.action = "move_piece";
ob.piece = "white_queen";
ob.y_tile = 7;
ob.x_tile = 6;
es.sendMove("all", ob);
Here is an example of how you could send an array to everyone in your room.
var ob:Object = new Object();
ob.action = "ListOfFriends";
ob.friends = new Array ("Jobe", "Mike", "Robert", "Kelly");
es.sendMove("all", ob);
What follows is an example of a private game move that is send to only 2 other people. Let's say they are on your team in the game. You are giving them some ammo.
var ob:Object = new Object();
ob.action = "GiveAmmo";
ob.ammoType = "Uzi";
es.sendMove(["mike", "robert"], ob);

sendRaw

public function sendRaw(str: String)
Sends a raw unchanged string to a plugin

Used in conjunction with registerRawHandler, this advanced method is used to send a raw message directly to ElectroServer. It won't be re-formatted by the ElectroServer class. It's just sent as-is. ElectroServer captures it and forwards it to the plugin specified when you used registerRawHandler.

Parameters:
str
The raw string to send.
Example:
es.sendRaw("t|23|f|90");

setDebug

public function setDebug(val: Boolean)
Sets the debug property to true or false. If true it traces all inbound/outbound messages

This is used to trace all inbound and outbound messages used to communicate with ElectroServer. By default it is not enabled. It can be very useful when debugging issues. See also getDebug.

Parameters:
val
Boolean value. If true then debugging is enabled.
Example:
es.setDebug(true);

setIP

public function setIP(tempIP: String)
Sets the IP address to use when connecting to ElectroServer

Sets the ip address of ElectroServer. When ElectroServer 3 is started (on a physical server somewhere or on your local machine) it binds to a specific IP address. You must specify this IP address and the port in order to connect to ElectroServer.

Parameters:
tempIP
The ip address to connect to.
Example:
es.setIP("127.0.0.1");
es.setPort(9875);
es.connect();

setModeratorLabel

public function setModeratorLabel(val: Boolean,
 str: String)
Sets the moderator label to be appended to the front of a the name of all moderators

All user objects have a 'label' property. If that user is a moderator its label can look different than other users. To do that use this method. For instance, a moderator may have a label that looks like this "[mod] Jobe". Over all, this isn't used very often.

Parameters:
val
A Boolean value. If true then it will show the moderator label.
str
The string to append to the front of a moderator's label
Example:
es.setModeratorLabel(true, "[mod]");

setPort

public function setPort(tempPort: Number)
Sets the port to use when connecting to ElectroServer

Sets the port that the class will use to connect to ElectroServer. ElectroServer must be listening on this port

Parameters:
tempPort
The port to use
Example:
es.setIP("127.0.0.1");
es.setPort(9875);
es.connect();

updateUserVariable

public function updateUserVariable(name: String,
 value: String)
Updates a user variable

This updates an existing user variable. It works just like creating a user variable. See also createUserVariable, deleteUserVariable.

Parameters:
name
The name of the variable to update
value
The new value of the variable
Example:
es.updateUserVariable("myIcon", "sadFace");


The documentation was generated from the following file:


Generated on 1/18/2006 8:38:58 PM by AS2Doc